-
-
Notifications
You must be signed in to change notification settings - Fork 33.7k
doc, module: change stability of async customization hooks to experimental #60302
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc, module: change stability of async customization hooks to experimental #60302
Conversation
|
Review requested:
|
686506b to
31c0694
Compare
df81a7d to
f036b18
Compare
doc/api/module.md
Outdated
| <!-- type=misc --> | ||
| > Stability: 1.2 - Release candidate (asynchronous version) | ||
| > Stability: 1 - Experimental (asynchronous version) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any stability level 1.x is experimental. See https://nodejs.org/docs/latest/api/documentation.html#stability-index
We don’t really have a level for “pending removal” so maybe the most appropriate level is the most experimental one:
| > Stability: 1 - Experimental (asynchronous version) | |
| > Stability: 1.0 - Early development (asynchronous version) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's not early development though
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think deprecated would be the state for pending removal but that seems too early to me.
I selected a similar state/wording as for async_hooks (except the migration hints) because it seems very similar:
- no 100% replacement as of now
- works fine for some usecases
- has flows which can't/are not planned to be fixed
- high overhead at least in some cases
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It was decided that "deprecated" was reserved for stable features:
Lines 48 to 49 in 38bf955
| > Experimental features leave the experimental status typically either by | |
| > graduating to stable, or are removed without a deprecation cycle. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe just create a new stage like 1.9 - Pending removal? And we can add a note next to it that the sync hooks are the intended replacement.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If neither 1.2 - Release candidate nor 1.0 - Early Development makes sense, maybe 1.1 - Active development ?
I feel that whether/when to remove it would be a different question due to the existing usage, but it somewhat certain that even if it stays, it would have to have changes in order to be really functional - there are too many quirks right now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that 1.1 - Active development is better than 1.2, but I think just making a new Pending removal stage would be better still. Worst of all would be going to just 1 - Experimental, as that doesn’t provide any guidance. Having a detailed note is good, but there’s tooling built around our docs and so I think it’s better if the most important information (that this is pending removal) is presented in a structured data way that tooling can understand, rather than contained only within a natural English note.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think this PR is the right place to change the Stability index content. This can be done in a separate issue if we think this is needed. There are other places which could benefit from this (async_hooks, trace events, wasi).
Additionally I don't want to start the removal discussion as I can't tell if it will ever happen. It's experimental and according to the Stability index it can be removed at any time without a deprecation cycle. Not saying that we should do that but that is what is written there.
Reading the Stability index again it seems 1.1 fits well. While name of 1.1 includes active the detailed text says Experimental features at this stage are nearing minimum viability. which fits. There is no definition of "active" in the sense of PR count/month,...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
There is ongoing work to replace async customization hooks by a synchronous variant. As a result bugs/design flaws or the async variant (thread leak, overhead) are not addressed. Adapt stability index to avoid wrong assumptions they might move to stable. Refs: nodejs/loaders#201 Refs: nodejs/loaders#198
Co-authored-by: Antoine du Hamel <[email protected]>
ae4d294 to
1690620
Compare
|
FWIW #59666 lists some of the existing bugs in the async cutomization hooks that can explain why this is a bit too far from "release candidate" (they are not yet documented as "known caveats", but have existed from v20) |
|
@mcollina you added tsc-agenda label at the same time as you approved. |
|
FYI was done at the TSC meeting; remove the tsc-agenda lebel. |
|
Landed in a59706f |
There is ongoing work to replace async customization hooks by a synchronous variant. As a result bugs/design flaws or the async variant (thread leak, overhead) are not addressed. Adapt stability index to avoid wrong assumptions they might move to stable. Refs: nodejs/loaders#201 Refs: nodejs/loaders#198 PR-URL: #60302 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Darshan Sen <[email protected]>
There is ongoing work to replace async customization hooks by a synchronous variant. As a result bugs/design flaws or the async variant (thread leak, overhead) are not addressed. Adapt stability index to avoid wrong assumptions they might move to stable. Refs: nodejs/loaders#201 Refs: nodejs/loaders#198 PR-URL: #60302 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Darshan Sen <[email protected]>
There is ongoing work to replace async customization hooks by a synchronous variant. As a result bugs/design flaws or the async variant (thread leak, overhead) are not addressed. Adapt stability index to avoid wrong assumptions they might move to stable. Refs: nodejs/loaders#201 Refs: nodejs/loaders#198 PR-URL: #60302 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Darshan Sen <[email protected]>
This MR contains the following updates: | Package | Update | Change | |---|---|---| | [node](https://nodejs.org) ([source](https://github.com/nodejs/node)) | minor | `25.0.0` -> `25.1.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>nodejs/node (node)</summary> ### [`v25.1.0`](https://github.com/nodejs/node/releases/tag/v25.1.0): 2025-10-28, Version 25.1.0 (Current), @​aduh95 [Compare Source](nodejs/node@v25.0.0...v25.1.0) ##### Notable Changes - \[[`4395fe14b9`](nodejs/node@4395fe14b9)] - **(SEMVER-MINOR)** **http**: add optimizeEmptyRequests server option (Rafael Gonzaga) [#​59778](nodejs/node#59778) - \[[`2e55c6ad04`](nodejs/node@2e55c6ad04)] - **(SEMVER-MINOR)** **sqlite**: allow setting defensive flag (Bart Louwers) [#​60217](nodejs/node#60217) - \[[`f437204491`](nodejs/node@f437204491)] - **(SEMVER-MINOR)** **src**: add watch config namespace (Marco Ippolito) [#​60178](nodejs/node#60178) ##### Commits - \[[`bb27766bd5`](nodejs/node@bb27766bd5)] - **benchmark**: improve cpu.sh for safety and usability (Nam Yooseong) [#​60162](nodejs/node#60162) - \[[`e600711c20`](nodejs/node@e600711c20)] - **benchmark**: add benchmark for leaf source text modules (Joyee Cheung) [#​60205](nodejs/node#60205) - \[[`1bbcdf9039`](nodejs/node@1bbcdf9039)] - **benchmark**: add vm.SourceTextModule benchmark (Joyee Cheung) [#​59396](nodejs/node#59396) - \[[`22fa6bd28b`](nodejs/node@22fa6bd28b)] - **build**: ibmi follow aix visibility (SRAVANI GUNDEPALLI) [#​60360](nodejs/node#60360) - \[[`931028400e`](nodejs/node@931028400e)] - **build**: use call command when calling python configure (Jacob Nichols) [#​60098](nodejs/node#60098) - \[[`17fde3f3d1`](nodejs/node@17fde3f3d1)] - **build**: build v8 with -fvisibility=hidden -fvisibility-inlines-hidden (Joyee Cheung) [#​56290](nodejs/node#56290) - \[[`04cc7aae5e`](nodejs/node@04cc7aae5e)] - **build**: remove V8\_COMPRESS\_POINTERS\_IN\_ISOLATE\_CAGE defs (Joyee Cheung) [#​60296](nodejs/node#60296) - \[[`8a2053060d`](nodejs/node@8a2053060d)] - **crypto**: update root certificates to NSS 3.116 (Node.js GitHub Bot) [#​59956](nodejs/node#59956) - \[[`fe91c0f755`](nodejs/node@fe91c0f755)] - **deps**: update simdjson to 4.0.7 (Node.js GitHub Bot) [#​59883](nodejs/node#59883) - \[[`aacfc0d212`](nodejs/node@aacfc0d212)] - **deps**: update corepack to 0.34.1 (Node.js GitHub Bot) [#​60314](nodejs/node#60314) - \[[`8596891a71`](nodejs/node@8596891a71)] - **deps**: update inspector\_protocol to [`af7f5a8`](nodejs/node@af7f5a8) (Node.js GitHub Bot) [#​60312](nodejs/node#60312) - \[[`21bcd0eb2f`](nodejs/node@21bcd0eb2f)] - **deps**: V8: cherry-pick [`3d0f462`](nodejs/node@3d0f462a17ff) (Joyee Cheung) [#​59396](nodejs/node#59396) - \[[`673558501c`](nodejs/node@673558501c)] - **deps**: update googletest to [`279f847`](nodejs/node@279f847) (Node.js GitHub Bot) [#​60219](nodejs/node#60219) - \[[`425a1879b1`](nodejs/node@425a1879b1)] - **doc**: mention more codemods in `deprecations.md` (Augustin Mauroy) [#​60243](nodejs/node#60243) - \[[`563e1317f3`](nodejs/node@563e1317f3)] - **doc**: remove unnecessary statement of web storage (Deokjin Kim) [#​60363](nodejs/node#60363) - \[[`064c8c5cfd`](nodejs/node@064c8c5cfd)] - **doc**: add missing CAA type to dns.resolveAny() & dnsPromises.resolveAny() (Jimmy Leung) [#​58899](nodejs/node#58899) - \[[`99e357af35`](nodejs/node@99e357af35)] - **doc**: use `any` for `worker_threads.Worker` 'error' event argument `err` (Jonas Geiler) [#​60300](nodejs/node#60300) - \[[`8ccff0d934`](nodejs/node@8ccff0d934)] - **doc**: update decorator documentation to reflect actual policy (Muhammad Salman Aziz) [#​60288](nodejs/node#60288) - \[[`bac70c6ef3`](nodejs/node@bac70c6ef3)] - **doc**: document wildcard supported by tools/test.py (Joyee Cheung) [#​60265](nodejs/node#60265) - \[[`8492bc6a88`](nodejs/node@8492bc6a88)] - **doc**: add --heap-snapshot-on-oom to useful v8 flag (jakecastelli) [#​60260](nodejs/node#60260) - \[[`0f0d3c0e47`](nodejs/node@0f0d3c0e47)] - **doc**: fix `blob.bytes()` heading level (XTY) [#​60252](nodejs/node#60252) - \[[`8c8525cf93`](nodejs/node@8c8525cf93)] - **doc**: fix not working code example in vm docs (Artur Gawlik) [#​60224](nodejs/node#60224) - \[[`8a6de3866c`](nodejs/node@8a6de3866c)] - **doc, assert**: correct order of changes entries (Gerhard Stöbich) [#​60304](nodejs/node#60304) - \[[`6bacb6555a`](nodejs/node@6bacb6555a)] - **doc, module**: change async customization hooks to experimental (Gerhard Stöbich) [#​60302](nodejs/node#60302) - \[[`6f3b16df16`](nodejs/node@6f3b16df16)] - **esm**: use index-based resolution callbacks (Joyee Cheung) [#​59396](nodejs/node#59396) - \[[`95644a432c`](nodejs/node@95644a432c)] - **http**: lazy allocate cookies array (Robert Nagy) [#​59734](nodejs/node#59734) - \[[`4395fe14b9`](nodejs/node@4395fe14b9)] - **(SEMVER-MINOR)** **http**: add optimizeEmptyRequests server option (Rafael Gonzaga) [#​59778](nodejs/node#59778) - \[[`f1aa1eaaf5`](nodejs/node@f1aa1eaaf5)] - **inspector**: add network payload buffer size limits (Chengzhong Wu) [#​60236](nodejs/node#60236) - \[[`64fc625bf9`](nodejs/node@64fc625bf9)] - **inspector**: support handshake response for websocket inspection (Shima Ryuhei) [#​60225](nodejs/node#60225) - \[[`0ecbb806a8`](nodejs/node@0ecbb806a8)] - **lib**: fix typo in createBlobReaderStream (SeokHun) [#​60132](nodejs/node#60132) - \[[`ffec5927fd`](nodejs/node@ffec5927fd)] - **meta**: fix typo in test-shared workflow name (Ronit Sabhaya) [#​60321](nodejs/node#60321) - \[[`a02897e157`](nodejs/node@a02897e157)] - **meta**: move one or more collaborators to emeritus (Node.js GitHub Bot) [#​60325](nodejs/node#60325) - \[[`59223a7831`](nodejs/node@59223a7831)] - **meta**: loop userland-migrations in deprecations (Chengzhong Wu) [#​60299](nodejs/node#60299) - \[[`2d48d17696`](nodejs/node@2d48d17696)] - **module**: refactor and clarify async loader hook customizations (Joyee Cheung) [#​60278](nodejs/node#60278) - \[[`be1b84fd93`](nodejs/node@be1b84fd93)] - **module**: handle null source from async loader hooks in sync hooks (Joyee Cheung) [#​59929](nodejs/node#59929) - \[[`063fbd87d3`](nodejs/node@063fbd87d3)] - **msi**: fix WiX warnings (Stefan Stojanovic) [#​60251](nodejs/node#60251) - \[[`2e55c6ad04`](nodejs/node@2e55c6ad04)] - **(SEMVER-MINOR)** **sqlite**: allow setting defensive flag (Bart Louwers) [#​60217](nodejs/node#60217) - \[[`dc93d6988a`](nodejs/node@dc93d6988a)] - **src**: fix timing of snapshot serialize callback (Joyee Cheung) [#​60434](nodejs/node#60434) - \[[`267e1b3817`](nodejs/node@267e1b3817)] - **src**: add COUNT\_GENERIC\_USAGE utility for tests (Joyee Cheung) [#​60434](nodejs/node#60434) - \[[`4a5d7a4c2a`](nodejs/node@4a5d7a4c2a)] - **src**: conditionally disable source phase imports by default (Shelley Vohr) [#​60364](nodejs/node#60364) - \[[`f437204491`](nodejs/node@f437204491)] - **(SEMVER-MINOR)** **src**: add watch config namespace (Marco Ippolito) [#​60178](nodejs/node#60178) - \[[`36837fa0f9`](nodejs/node@36837fa0f9)] - **src**: use cached primordials\_string (Sohyeon Kim) [#​60255](nodejs/node#60255) - \[[`df8396ad37`](nodejs/node@df8396ad37)] - **src**: replace Environment::GetCurrent with args.GetIsolate (Sohyeon Kim) [#​60256](nodejs/node#60256) - \[[`5dd670b2b9`](nodejs/node@5dd670b2b9)] - **src**: initial enablement of IsolateGroups (James M Snell) [#​60254](nodejs/node#60254) - \[[`afdb362933`](nodejs/node@afdb362933)] - **src**: use `Utf8Value` and `TwoByteValue` instead of V8 helpers (Anna Henningsen) [#​60244](nodejs/node#60244) - \[[`a40e533e72`](nodejs/node@a40e533e72)] - **src**: add a default branch for module phase (Chengzhong Wu) [#​60261](nodejs/node#60261) - \[[`42729f07ee`](nodejs/node@42729f07ee)] - **src**: stop using deprecated v8::Context::GetIsolate (Michaël Zasso) [#​60223](nodejs/node#60223) - \[[`7a6542c205`](nodejs/node@7a6542c205)] - **test**: skip failing test on macOS 15.7+ (Antoine du Hamel) [#​60419](nodejs/node#60419) - \[[`29a5855a4f`](nodejs/node@29a5855a4f)] - **test**: ensure assertions are reachable in `test/addons` (Antoine du Hamel) [#​60142](nodejs/node#60142) - \[[`12773d19c4`](nodejs/node@12773d19c4)] - **test**: increase debugger waitFor timeout on macOS (Chengzhong Wu) [#​60367](nodejs/node#60367) - \[[`0b38de3e9e`](nodejs/node@0b38de3e9e)] - **test**: put helper in test-runner-output into common (Joyee Cheung) [#​60330](nodejs/node#60330) - \[[`6de2407c44`](nodejs/node@6de2407c44)] - **test**: fix small compile warning in test\_network\_requests\_buffer.cc (xiaocainiao633) [#​60281](nodejs/node#60281) - \[[`4b23ac8613`](nodejs/node@4b23ac8613)] - **test**: fix status when compiled without inspector (Antoine du Hamel) [#​60289](nodejs/node#60289) - \[[`a07f32e326`](nodejs/node@a07f32e326)] - **test**: split test-runner-watch-mode-kill-signal (Joyee Cheung) [#​60298](nodejs/node#60298) - \[[`30451d32d7`](nodejs/node@30451d32d7)] - **test**: fix incorrect calculation in test-perf-hooks.js (Joyee Cheung) [#​60271](nodejs/node#60271) - \[[`e3c3b48f1c`](nodejs/node@e3c3b48f1c)] - **test**: ignore EPIPE errors in https proxy invalid URL test (Joyee Cheung) [#​60269](nodejs/node#60269) - \[[`405a9c4c5f`](nodejs/node@405a9c4c5f)] - **test**: parallelize test-without-async-context-frame correctly (Joyee Cheung) [#​60273](nodejs/node#60273) - \[[`ffeebebc71`](nodejs/node@ffeebebc71)] - **test**: make test-worker-prof more tolerant (Joyee Cheung) [#​60272](nodejs/node#60272) - \[[`26b01bf170`](nodejs/node@26b01bf170)] - **test**: skip sea tests on x64 macOS (Joyee Cheung) [#​60250](nodejs/node#60250) - \[[`8caae1a05b`](nodejs/node@8caae1a05b)] - **test**: move sea tests into test/sea (Joyee Cheung) [#​60250](nodejs/node#60250) - \[[`3d183e3e9f`](nodejs/node@3d183e3e9f)] - **test,crypto**: fix conditional SHA3-\* skip on BoringSSL (Filip Skokan) [#​60379](nodejs/node#60379) - \[[`e83dbcba94`](nodejs/node@e83dbcba94)] - **test,crypto**: sha3 algorithms aren't supported with BoringSSL (Shelley Vohr) [#​60374](nodejs/node#60374) - \[[`3d89331496`](nodejs/node@3d89331496)] - **test\_runner**: use module.registerHooks in module mocks (Joyee Cheung) [#​60326](nodejs/node#60326) - \[[`377e8ce85a`](nodejs/node@377e8ce85a)] - **tls**: avoid external memory leak on invalid protocol versions (Shelley Vohr) [#​60390](nodejs/node#60390) - \[[`ae4858c1f6`](nodejs/node@ae4858c1f6)] - **tools**: add an option to generate lighter archives (Antoine du Hamel) [#​60294](nodejs/node#60294) - \[[`cb615b1a2e`](nodejs/node@cb615b1a2e)] - **tools**: skip test-shared workflow for draft MRs (Michaël Zasso) [#​60365](nodejs/node#60365) - \[[`03b034731e`](nodejs/node@03b034731e)] - **tools**: disable inspector on macOS-shared to reduce flakiness (Antoine du Hamel) [#​60320](nodejs/node#60320) - \[[`f402b4e1d1`](nodejs/node@f402b4e1d1)] - **tools**: show diff alongside the error in Nix linter (Antoine du Hamel) [#​60301](nodejs/node#60301) - \[[`5d5c8483fb`](nodejs/node@5d5c8483fb)] - **tools**: run CI with shared libs on GHA (Antoine du Hamel) [#​60121](nodejs/node#60121) - \[[`e8fdd8d2e8`](nodejs/node@e8fdd8d2e8)] - **tools**: update gyp-next to 0.20.5 (Node.js GitHub Bot) [#​60313](nodejs/node#60313) - \[[`6e8b029a21`](nodejs/node@6e8b029a21)] - **tools**: limit inspector protocol MR title length (Chengzhong Wu) [#​60324](nodejs/node#60324) - \[[`a5073086c6`](nodejs/node@a5073086c6)] - **tools**: fix inspector\_protocol updater (Chengzhong Wu) [#​60277](nodejs/node#60277) - \[[`47fa765bff`](nodejs/node@47fa765bff)] - **tools**: optimize wildcard execution in tools/test.py (Joyee Cheung) [#​60266](nodejs/node#60266) - \[[`11ebb0447d`](nodejs/node@11ebb0447d)] - **tools**: add C++ lint rule to avoid using `String::Utf8Value` (Anna Henningsen) [#​60244](nodejs/node#60244) - \[[`14f3189670`](nodejs/node@14f3189670)] - **tools**: add inspector\_protocol updater (Chengzhong Wu) [#​60245](nodejs/node#60245) - \[[`ef4c596fc6`](nodejs/node@ef4c596fc6)] - **typings**: add missing properties and method in Worker (Woohyun Sung) [#​60257](nodejs/node#60257) - \[[`09ae6fc065`](nodejs/node@09ae6fc065)] - **typings**: add missing properties in HTTPParser (Woohyun Sung) [#​60257](nodejs/node#60257) - \[[`9ecaf41f8e`](nodejs/node@9ecaf41f8e)] - **typings**: delete undefined property in ConfigBinding (Woohyun Sung) [#​60257](nodejs/node#60257) - \[[`4a86016e86`](nodejs/node@4a86016e86)] - **util**: use more defensive code when inspecting error objects (Antoine du Hamel) [#​60139](nodejs/node#60139) - \[[`9e6d6cec59`](nodejs/node@9e6d6cec59)] - **util**: mark special properties when inspecting them (Ruben Bridgewater) [#​60131](nodejs/node#60131) - \[[`79b2387fd9`](nodejs/node@79b2387fd9)] - **vm**: make vm.Module.evaluate() conditionally synchronous (Joyee Cheung) [#​60205](nodejs/node#60205) - \[[`e5559f3be3`](nodejs/node@e5559f3be3)] - **win**: upgrade Visual Studio workload from 2019 to 2022 (Jiawen Geng) [#​60318](nodejs/node#60318) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0MS4xNjQuMSIsInVwZGF0ZWRJblZlciI6IjQxLjE2NC4xIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiXX0=-->
There is ongoing work to replace async customization hooks by a synchronous variant. As a result bugs/design flaws or the async variant (thread leak, overhead) are not addressed.
Adapt stability index to avoid wrong assumptions they might move to stable.
Refs: nodejs/loaders#201
Refs: nodejs/loaders#198